Upgrade a2a to spec v0.2.3 #2144

physicsrob · 2025-07-07T12:29:56Z

Summary

This PR upgrades the fasta2a implementation from A2A protocol v0.1 to v0.2.3. The upgrade introduces significant improvements to conversation continuity through the new A2A context_id concept and implements a dual-purpose storage architecture for efficient multi-turn conversations.

Note: This is a breaking change and is not backward compatible. However, given the limited adoption of the previous protocol version, this change prioritizes alignment with the current A2A specification.

Key Changes

Protocol Updates

Renamed endpoint from tasks/send to message/send
Replaced type fields with kind throughout the schema
Switched from client-generated to server-generated task IDs
Updated Message and Task structures to v0.2.3 format
Replaced session_id with context_id for conversation continuity and adherence to A2A spec

Conversation Model Enhancements

Context-based conversations: Introduced context_id to group related messages across multiple tasks
Dual-purpose storage:
- Task storage maintains A2A protocol compliance
- Context storage preserves rich agent state (tool calls, thinking, etc.)
Conversation continuity: Multi-turn conversations now span multiple task executions
Storage API improvements:
- Added update_context() and get_context() methods for agent-specific state
- Modified update_task() to accept new_messages and new_artifacts lists
- Removed deprecated message parameter from update_task()

Schema Enhancements

Added id field to PushNotificationConfig for server-assigned identifiers
Added new task states: rejected and auth-required
Implemented proper file handling with FileWithBytes and FileWithUri
Added type guards (is_task(), is_message()) for better type safety

Artifact Improvements

Support for both TextPart and DataPart in artifacts based on output type
Added unique artifact IDs for better tracking
Dual output approach:
- Agent results stored as Messages (for conversation history)
- Agent results stored as Artifacts (for durable outputs)
Enhanced metadata including JSON schema for Pydantic models

AgentWorker Implementation

Loads full pydantic-ai message history from context storage
Preserves complete conversation state including tool calls and responses
Converts between A2A and pydantic-ai message formats as needed
Ensures task state validation (only processes 'submitted' tasks)

Test Changes

Updated all tests to work with the new protocol format
Added test for Pydantic model outputs with JSON schema metadata
Added test for monotonic message history growth across contexts
Renamed test directory from tests/fasta2a/ to tests/test_fasta2a/ to avoid import conflicts

Breaking Changes

Storage API changes:
- New required methods: update_context() and get_context()
- Task submission now requires context_id
- update_task() signature changed
Message format changes:
- type → kind throughout
- session_id → context_id
- New required fields in various message types
Endpoint changes:
- tasks/send → message/send

- Update protocol methods: tasks/send → message/send - Replace 'type' with 'kind' throughout schema - Replace 'session_id' with 'context_id' for conversation tracking - Add Message and Part types (TextPart, FilePart, DataPart) - Implement dual message/artifact approach for agent outputs - Add metadata to artifacts including type info and JSON schema - Add proper error handling with task state updates - Add NotImplementedError stubs for streaming methods - Rename test directory to avoid import conflicts

- Test that Pydantic model outputs are correctly serialized as DataPart - Verify metadata includes type name and JSON schema - Ensure dual message/artifact approach works for complex types - Confirm that both message history and artifacts contain the data

- Add update_context() and get_context() methods to Storage - Store full pydantic-ai message history (including tool calls) in context - Preserve conversation state across multiple tasks with same context_id - Update docs to explain task vs context distinction - Add test for monotonic message history growth - Clean up run_task: remove history_length, add state check, fix comments

hyperlint-ai · 2025-07-07T12:30:12Z

PR Change Summary

Upgraded the fasta2a implementation to A2A protocol v0.2.3, introducing significant enhancements for conversation continuity and a dual-purpose storage architecture.

Renamed endpoint from tasks/send to message/send and replaced type fields with kind in the schema.
Introduced context_id for improved conversation continuity and updated storage architecture for multi-turn conversations.
Implemented new methods in the Storage API and made breaking changes to message formats and task submissions.

Modified Files

docs/a2a.md

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

physicsrob · 2025-07-07T12:36:49Z

@Kludex
I noticed your message "Working on this" -- just FYI I spend a bunch of time on yesterday working on pulling out just the upgrade. Here's a draft PR:.

I was going to spend a couple more hours cleaning up before submitting a PR, but it's fairly close. I did end up changing the approach pretty significantly to conversation continuity. There was a pretty big fundamental limitation in the previous incarnation: Since only A2A messages were persisted / retrieved that meant that follow-up tasks could only see messages that were converted to/from A2A's format, and that's fundamentally going to be lossy. In particular tool call results from previous tasks are going to be invisible to the agent for subsequent calls. I personally think that's a big limitation worth addressing.

The one area I'm very much less convinced of my approach: Whether final results should be an artifact or both an artifact and a message. Right now in the PR it generates both. But I was probably going to make it just an artifact

Kludex · 2025-07-07T12:44:10Z

fasta2a/fasta2a/applications.py

+        elif a2a_request['method'] == 'tasks/send':  # type: ignore[comparison-overlap]
+            # Legacy method - no longer supported
+            raise NotImplementedError('tasks/send is deprecated. Use message/send instead.')


There's no need for this. Just drop it.

fasta2a/fasta2a/applications.py

docs/a2a.md

Kludex · 2025-07-07T12:48:21Z

fasta2a/fasta2a/client.py


-        payload = SendTaskRequest(jsonrpc='2.0', id=None, method='tasks/send', params=task)
-        content = a2a_request_ta.dump_json(payload, by_alias=True)
+        request_id = str(uuid.uuid4())


What is this ID? Is it the request_id?

Yes, this is the request_id for JSON-RPC. Let me know if you think a clarifying comment would be helpful, or if there's something off about the variable names

Kludex · 2025-07-07T12:51:23Z

fasta2a/fasta2a/schema.py

+    description: NotRequired[str]
+    """A description of the data."""


I don't see any description on the DataPart on the specification.

Suggested change

description: NotRequired[str]

"""A description of the data."""

yeah not sure how that ended up there. Fixed. thx.

Kludex · 2025-07-07T12:52:01Z

fasta2a/fasta2a/schema.py

 """A fully formed piece of content exchanged between a client and a remote agent as part of a Message or an Artifact.

 Each Part has its own content type and metadata.
 """

-TaskState: TypeAlias = Literal['submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'unknown']
+TaskState: TypeAlias = Literal[
+    'submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required'


Unknown is still in the specification.

Suggested change

'submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required'

'submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required', 'unknown'

Kludex · 2025-07-07T12:53:53Z

fasta2a/fasta2a/schema.py

+def is_task(response: Task | Message) -> TypeGuard[Task]:
+    """Type guard to check if a response is a Task."""
+    return 'id' in response and 'status' in response and 'context_id' in response and response.get('kind') == 'task'
+
+
+def is_message(response: Task | Message) -> TypeGuard[Message]:
+    """Type guard to check if a response is a Message."""
+    return 'role' in response and 'parts' in response and response.get('kind') == 'message'


This seems to be for the tests. There's no need to include those in the schema.

Also, on the tests, just check the kind is task or message. It's enough to infer the type for the type checker.

Kludex · 2025-07-07T12:54:34Z

fasta2a/fasta2a/task_manager.py

+    async def send_message(self, request: SendMessageRequest) -> SendMessageResponse:
+        """Send a message using the A2A v0.2.3 protocol."""
+        request_id = request['id']
+        task_id = str(uuid.uuid4())


This should be generated in the submit_task - so we have the task id in the task object after.

Agreed. 👍

Kludex · 2025-07-07T12:54:53Z

fasta2a/fasta2a/task_manager.py

+        """Stream messages using Server-Sent Events. Not implemented."""
+        raise NotImplementedError('message/stream method is not implemented yet.')


Suggested change

"""Stream messages using Server-Sent Events. Not implemented."""

raise NotImplementedError('message/stream method is not implemented yet.')

"""Stream messages using Server-Sent Events."""

raise NotImplementedError('message/stream method is not implemented yet.')

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

…acts to conform

…ation - Change DataPart.data type from Any to dict[str, Any] per A2A spec - Wrap non-dict agent results as {"result": <data>} for consistency - Remove DataPart.description field (not in spec) - Improve message vs artifact separation: - String outputs appear in both messages and artifacts - Structured data only appears as artifacts (not duplicated in messages) - Update tests to reflect new behavior - Update docs to clarify artifact handling

physicsrob · 2025-07-08T05:59:50Z

@Kludex Just finished my updates.

Changes:

I believe I addressed all of your first round of feedback (thanks!)
A little bit of misc tidying on my part
Changed the logic for creating for handling agent results. The new logic is that string results are treated as messages AND also result in a TextPart artifact, whereas structured results are treated as artifacts only and do not show up in the message history.

Kludex

I'm reverting the test name directory change. Please avoid changes outside the scope of the PR.

Kludex · 2025-07-08T06:40:12Z

fasta2a/fasta2a/applications.py

+        elif a2a_request['method'] == 'message/stream':
+            raise NotImplementedError(
+                'message/stream method is not implemented yet. Streaming support will be added in a future update.'
+            )


We already handle all the non supported methods a bit down here, so I'll drop this for now.

Kludex · 2025-07-08T06:41:11Z

fasta2a/fasta2a/client.py

+    ) -> SendMessageResponse:
+        """Send a message using the A2A protocol.
+
+        Returns a JSON-RPC response containing either a result (Task | Message) or an error.


I understand by the spec is possible to return both, but we always return Task.

Kludex · 2025-07-08T06:47:19Z

fasta2a/fasta2a/schema.py

+    data: str
+    """The base64 encoded data."""


It's bytes now.

Kludex · 2025-07-08T06:49:51Z

fasta2a/fasta2a/storage.py

+        """Update the state of a task. Appends artifacts and messages, if specified."""
+
+    @abstractmethod
+    async def update_context(self, context_id: str, context: Any) -> None:


Any is usually a sign that something is wrong.

We can make storage to be generic on context.

Kludex · 2025-07-08T06:52:30Z

pydantic_ai_slim/pydantic_ai/_a2a.py

+        if task is None:
+            raise ValueError(f'Task {params["id"]} not found')
+        if 'context_id' not in task:
+            raise ValueError('Task must have a context_id')


A context_id is always provided in a task - by type definition.

Kludex · 2025-07-08T07:02:55Z

pydantic_ai_slim/pydantic_ai/_a2a.py

-        # TODO(Marcelo): We need to have a way to communicate when the task is set to `input-required`. Maybe
-        # a custom `output_type` with a `more_info_required` field, or something like that.


You removed my TODO, but I don't think we solve it?

Copilot

Pull Request Overview

This PR upgrades the A2A implementation from protocol v0.1 to v0.2.3 to support conversation continuity via a new context_id, dual-purpose storage for protocol tasks and agent context, and updated schema and endpoints to match the v0.2.3 specification.

Introduce context_id in place of session_id and rename endpoint tasks/send → message/send
Implement dual storage API with get_context()/update_context() alongside task storage
Enhance schema with new task states (rejected, auth-required), named artifacts (artifact_id), part discriminators (kind), and message identifiers

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_a2a.py	Updated tests to use `send_message`, `kind`, `message_id`, `context_id`, and validate JSON schema metadata
pydantic_ai_slim/pydantic_ai/agent.py	Swapped import of `Provider` → `AgentProvider` and updated `to_a2a()` parameter type
pydantic_ai_slim/pydantic_ai/_a2a.py	Overhauled `AgentWorker` to load/update context, convert messages and artifacts under new schema
fasta2a/fasta2a/worker.py	Minor signature rename in abstract `build_message_history`
fasta2a/fasta2a/task_manager.py	Replaced `send_task*` with `send_message`/`stream_message`, adapted parameters to v0.2.3
fasta2a/fasta2a/storage.py	Added `update_context()`/`get_context()`, switched storage to track `context_id` and new message/artifact lists
fasta2a/fasta2a/schema.py	Updated TypedDicts: added `kind`, `context_id`, `message_id`, new security schemes, task states, artifact IDs, etc.
fasta2a/fasta2a/client.py	Renamed `send_task` → `send_message`, updated request/response adapters
fasta2a/fasta2a/applications.py	Updated agent card schema and route handling for `message/send`
docs/a2a.md	Documented `context_id`, dual-purpose storage, and new artifact behavior

Comments suppressed due to low confidence (1)

fasta2a/fasta2a/task_manager.py:114

[nitpick] The client still uses tasks/get for retrieval but message/send for creation, which may be confusing. For symmetry with message/send, consider renaming tasks/get → message/get or update documentation to clarify the mixed-use.

    async def send_message(self, request: SendMessageRequest) -> SendMessageResponse:

Copilot · 2025-07-08T07:31:16Z

pydantic_ai_slim/pydantic_ai/_a2a.py

+        if task is None:
+            raise ValueError(f'Task {params["id"]} not found')
+
+        # TODO(Marcelo): Should we lock `run_task` on the `context_id`?


Concurrent calls to run_task for the same context_id can race when updating context storage. Consider adding a per-context_id lock or semaphore to serialize context updates.

Copilot · 2025-07-08T07:31:17Z

pydantic_ai_slim/pydantic_ai/_a2a.py

+# Generic parameters are reversed compared to Agent because AgentDepsT has a default
+class AgentWorker(Worker, Generic[WorkerOutputT, AgentDepsT]):


[nitpick] The generic parameter order is reversed compared to Agent[Deps, Output]. Aligning the parameter order with Agent (i.e. Generic[AgentDepsT, WorkerOutputT]) would reduce confusion in type annotations.

Suggested change

# Generic parameters are reversed compared to Agent because AgentDepsT has a default

class AgentWorker(Worker, Generic[WorkerOutputT, AgentDepsT]):

# Aligning generic parameter order with Agent for consistency

class AgentWorker(Worker, Generic[AgentDepsT, WorkerOutputT]):

Copilot · 2025-07-08T07:31:17Z

pydantic_ai_slim/pydantic_ai/_a2a.py

+        else:
+            # For structured data, create a DataPart
+            try:
+                # Try using TypeAdapter for proper serialization


[nitpick] The fallback for structured data does not handle Pydantic BaseModel instances explicitly. Consider detecting isinstance(result, BaseModel) and using result.model_dump() (or equivalent) to preserve all fields.

pydantic_ai_slim/pydantic_ai/_a2a.py

holtskinner · 2025-07-08T16:20:21Z

NOTE: The A2A Protocol has been updated to v0.2.5, I would recommend adding in the updates between versions 0.2.3 and 0.2.5 https://github.com/a2aproject/A2A/releases

In addition, it could make sense to change FastA2A over to use the official A2A Python SDK under the hood to make it easier to update to newer versions of the protocol.

Kludex · 2025-07-08T17:13:58Z

NOTE: The A2A Protocol has been updated to v0.2.5, I would recommend adding in the updates between versions 0.2.3 and 0.2.5 a2aproject/A2A/releases

In addition, it could make sense to change FastA2A over to use the official A2A Python SDK under the hood to make it easier to update to newer versions of the protocol.

I'll do that.

I'm moving the FastA2A to its own repository.

physicsrob added 4 commits July 7, 2025 12:20

Fix types

3901954

Fix misattributed TODOs -- oops!

55f3ced

Kludex requested changes Jul 7, 2025

View reviewed changes

DouweM assigned Kludex Jul 7, 2025

physicsrob and others added 15 commits July 7, 2025 21:15

Update docs/a2a.md

0a95bf9

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update fasta2a/fasta2a/applications.py

5785901

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update fasta2a/fasta2a/applications.py

d1ff90a

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update fasta2a/fasta2a/schema.py

15df524

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update fasta2a/fasta2a/schema.py

1a245a7

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update fasta2a/fasta2a/schema.py

ffe8a6e

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Update docs

5fd0dde

Remove deprecation exception

872714e

Remove deprecation exception

9372d3c

Change DataPart data type back to dict[str, Any]; Update result artif…

c5dd525

…acts to conform

More PR feedback on spec

a131482

Remove is_task/is_message

2f05b6c

Address PR feedback on task_manager

a23582a

Update tests for requiring message_id

06b2d88

physicsrob changed the title ~~[DRAFT] Upgrade a2a v0.2.3~~ Upgrade a2a to spec v0.2.3 Jul 8, 2025

physicsrob mentioned this pull request Jul 8, 2025

Upgrade fasta2a to A2A v0.2.3 and Enable Dependency Injection #2103

Closed

Kludex reviewed Jul 8, 2025

View reviewed changes

Kludex added 2 commits July 8, 2025 09:06

apply my comments

36fc9e8

Merge remote-tracking branch 'origin/main' into part1-upgrade-a2a-v0.2.3

a984a68

update types with claude

d50cd8e

Kludex requested a review from Copilot July 8, 2025 07:28

Copilot AI reviewed Jul 8, 2025

View reviewed changes

update tests

d24fcca

Kludex reviewed Jul 8, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/_a2a.py Outdated Show resolved Hide resolved

Kludex added 2 commits July 8, 2025 12:47

update code

270872c

coverage

7971e34

Merge branch 'main' into part1-upgrade-a2a-v0.2.3

3a4c4c6

		description: NotRequired[str]
		"""A description of the data."""

	'submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required'
	'submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required', 'unknown'

		"""Stream messages using Server-Sent Events. Not implemented."""
		raise NotImplementedError('message/stream method is not implemented yet.')

		# TODO(Marcelo): We need to have a way to communicate when the task is set to `input-required`. Maybe
		# a custom `output_type` with a `more_info_required` field, or something like that.

		# Generic parameters are reversed compared to Agent because AgentDepsT has a default
		class AgentWorker(Worker, Generic[WorkerOutputT, AgentDepsT]):

Upgrade a2a to spec v0.2.3 #2144

Are you sure you want to change the base?

Upgrade a2a to spec v0.2.3 #2144

Conversation

physicsrob commented Jul 7, 2025

Summary

Key Changes

Protocol Updates

Conversation Model Enhancements

Schema Enhancements

Artifact Improvements

AgentWorker Implementation

Test Changes

Breaking Changes

Uh oh!

hyperlint-ai bot commented Jul 7, 2025

PR Change Summary

Uh oh!

physicsrob commented Jul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

physicsrob commented Jul 8, 2025

Uh oh!

Kludex left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

holtskinner commented Jul 8, 2025 •

edited

Loading